<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Documenting your code &mdash; SIMULATeQCD 0.7 documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
      <link rel="stylesheet" href="../_static/togglebutton.css" type="text/css" />
      <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/jquery.js"></script>
        <script src="../_static/underscore.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/togglebutton.js"></script>
        <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Applications" href="../03_applications/applications.html" />
    <link rel="prev" title="Testing the code" href="testing.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #343131" >
            <a href="../index.html" class="icon icon-home"> SIMULATeQCD
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../01_gettingStarted/gettingStarted.html">Getting started</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contributions.html">Contributions</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="codeStyle.html">Our coding style</a></li>
<li class="toctree-l2"><a class="reference internal" href="git.html">How to do pull requests</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeStructure.html">General structure of the code</a></li>
<li class="toctree-l2"><a class="reference internal" href="templates.html">Template instantiation</a></li>
<li class="toctree-l2"><a class="reference internal" href="terminalIO.html">Terminal output &amp; terminating the program</a></li>
<li class="toctree-l2"><a class="reference internal" href="timer.html">Timing your code</a></li>
<li class="toctree-l2"><a class="reference internal" href="inputParameter.html">How to make an input parameter file</a></li>
<li class="toctree-l2"><a class="reference internal" href="memoryAllocation.html">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="multiGPU.html">Multi-GPU: Distribution of local lattices on the individual GPUs</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing the code</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Documenting your code</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../03_applications/applications.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../04_codeBase/codeBase.html">Code base</a></li>
<li class="toctree-l1"><a class="reference internal" href="../05_modules/modules.html">Modules</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu"  style="background: #343131" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">SIMULATeQCD</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
          <li><a href="contributions.html">Contributions</a> &raquo;</li>
      <li>Documenting your code</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/02_contributions/documenting.md.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section class="tex2jax_ignore mathjax_ignore" id="documenting-your-code">
<h1>Documenting your code<a class="headerlink" href="#documenting-your-code" title="Permalink to this headline"></a></h1>
<p>You have written some <a class="reference internal" href="codeStyle.html"><span class="doc std std-doc">readable code</span></a> that is
<a class="reference internal" href="codeStructure.html"><span class="doc std std-doc">reasonably organized</span></a> and, crucially, you
<a class="reference internal" href="testing.html"><span class="doc std std-doc">wrote a test for it</span></a>. There is only one thing left for you to do,
to make sure your code can be easily used and adapted by future developers:
You must document it!</p>
<p>To create some documentation, please navigate to <code class="docutils literal notranslate"><span class="pre">SIMULATeQCD/doc_src/</span></code>,
where you can find its source code. Our source code is written
using <a class="reference external" href="https://www.sphinx-doc.org/en/master/">Sphinx</a>, a python documentation
generator, combined with <a class="reference external" href="https://myst-parser.readthedocs.io/en/latest/">MyST</a>,
which is an extension for Sphinx supporting
<a class="reference external" href="https://daringfireball.net/projects/markdown/">Markdown</a>. You can follow those
links to learn more in detail about this syntax. With this documentation, we
just want to show you how to get started.</p>
<p>Before you compile the documentation, make sure you</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip install -r requirements.txt
</pre></div>
</div>
<p>If you would like to use the convenience function <code class="docutils literal notranslate"><span class="pre">docs_src/build/auto_compile.sh</span></code>,
you will also need to install the shell command <code class="docutils literal notranslate"><span class="pre">entr</span></code>.</p>
<section id="documentation-syntax">
<h2>Documentation syntax<a class="headerlink" href="#documentation-syntax" title="Permalink to this headline"></a></h2>
<p>You can <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">Title</span> <span class="pre">Your</span> <span class="pre">Page</span></code> like so. Each <code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">Heading</span></code> and <code class="docutils literal notranslate"><span class="pre">###</span> <span class="pre">Subheading</span></code> just
requires more pound symbols #.</p>
<p>Links to <code class="docutils literal notranslate"><span class="pre">[other</span> <span class="pre">documentation](path_to_documentation.md)</span></code> and to
<code class="docutils literal notranslate"><span class="pre">[webpages](https://www.web_link.org)</span></code> are accomplished in the same way.</p>
<p>To make a numbered list</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span>1. all you have to do
2. is start typing the numbers
3. like so
</pre></div>
</div>
<p>while an unordered list</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span>* is accomplished
* with asterisks
</pre></div>
</div>
<p>Boxes with short code snippets, like what you have seen above, are surrounded by the backtick `. Use three backticks to set
aside a block of code. You can specify the language for the code block so it correctly applies syntax highlighting.
Possible languages include, but are not limited to, <code class="docutils literal notranslate"><span class="pre">shell</span></code>, <code class="docutils literal notranslate"><span class="pre">python</span></code>, and <code class="docutils literal notranslate"><span class="pre">html</span></code>. (Besides following the web links above,
you can also see examples of the block code in action by looking into the documentation yourself.)</p>
<p>You can also add an image with this syntax:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span>![alt](../relative/path/to/image.png)
</pre></div>
</div>
<p>Note that not all file types for images are supported.</p>
</section>
<section id="compilation">
<h2>Compilation<a class="headerlink" href="#compilation" title="Permalink to this headline"></a></h2>
<p>Once you have added a <code class="docutils literal notranslate"><span class="pre">.md</span></code> file for your file, incorporate it into the most appropriate overarching <code class="docutils literal notranslate"><span class="pre">.md</span></code> file.
(For instance this one falls under <code class="docutils literal notranslate"><span class="pre">SIMULATeQCD/docs_src/02_contributions/contributions.md</span></code>.) You can see how you
did by compiling your code using <code class="docutils literal notranslate"><span class="pre">SIMULATeQCD/docs_src/build/compile.sh</span></code>. If you want to see how it looks, you can
open the <code class="docutils literal notranslate"><span class="pre">SIMULATeQCD/docs_src/build/index.html</span></code> file using your favorite browser. For example you could call
<code class="docutils literal notranslate"><span class="pre">firefox</span> <span class="pre">index.html</span></code> from the command line inside the <code class="docutils literal notranslate"><span class="pre">build</span></code> folder. When it looks nice, you can <a class="reference internal" href="git.html"><span class="doc std std-doc">commit your changes</span></a>.</p>
</section>
<section id="some-stylistic-guidelines-for-documentation">
<h2>Some stylistic guidelines for documentation<a class="headerlink" href="#some-stylistic-guidelines-for-documentation" title="Permalink to this headline"></a></h2>
<p>SIMULATeQCD is, at the moment, managed only by a handful of rather busy scientists. Nevertheless we would like to
have our code and documentation look professional and polished. This is difficult to achieve without someone
explicitly going through and checking for consistency; the best we can do is probably a bottom-up approach,
where we trust you to read these guidelines and try to keep them in mind. We will try to update this list as we think
of more things.</p>
<ol class="simple">
<li><p>Please use a spell checker.</p></li>
<li><p>Try to capitalize page titles and headings consistently. (For example on headings we are generally only capitalizing the first word, unless some grammatical rule would otherwise call for it.)</p></li>
<li><p>Set aside your code names and snippets in boxes.</p></li>
<li><p>Please link to other documentation such as research papers whenever you can.</p></li>
<li><p>Please include some easy examples to get started with what you wrote.</p></li>
<li><p>If you did some benchmarks, the documentation can be a good place to store that information.</p></li>
<li><p>Please try to keep your documentation up-to-date.</p></li>
<li><p>If you notice any mistakes in the documentation, please just make the change yourself, or if that is too complicated, please make an Issue.</p></li>
</ol>
</section>
</section>


           </div>
          </div>
          <footer>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2021, LatticeQCD.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>